Description

In this example, TRIDENT's digital signature API is used to generate the digital signature (PKCS #1) of a document with a mobile device. This operation is requested by a signbox Web application (signbox.safelayer.com) on behalf of a user (john.doe) who ordered that a Word document be signed. The user is logged in to the signbox app after having authenticated in TRIDENT with their password and is accessing the app with a mobile device. Signbox delegates the generating of the digital signature to TRIDENT. After it obtains the digital signature, signbox includes it in the electronic signature (CMS) of the document.

Signbox can detect whether the user is accessing with a desktop or a mobile device and in both cases allows the user to log in by delegating authentication to TRIDENT. If TRIDENT successfully authenticates the user, the signbox app gives the user the opportunity to select TRIDENT as the system for creating the signature each time they want to sign a document during the current session. If the user makes this selection and are accessing with a mobile device, the signbox app assumes that the signature key is on the mobile device the user is using and, therefore, that it must request from the TRIDENT the generation of an on-device signature. In this case, the signbox app takes into account the user's browser so it can appropriately adapt the user experience.

The signbox app is registered in the TRIDENT (txeidas.safelayer.com) as an OAuth 2.0 client application, which means it has an authorization server (main) and an identifier (signbox), and that it shares a secret with the platform (secret). Signbox has only one redirect URL registered: https://signbox.safelayer.com/oauth/callback.

It is assumed that signbox users have a mobile device (iOS ANDROID) with the BlueCard Mobile version of the Mobile ID application installed. We have also assumed that the editor of this application (BlueCard) is a certification services provider that provides a signature certificate to each user and that both the certificate and the associated signature key are stored on the user's mobile device. Lastly, it is also assumed that the TRIDENT platform to which signbox accesses was provisioned with the signing identities of the users. Thus, each user has a signing identity registered in TRIDENT corresponding to the signature key they have in their device that has the following attributes:

• The labels signbox, mobile and sign.

• The X.509 certificate issued by BlueCard for the signature key.

• The identifier of the mobile device where the signature key is stored.

Lastly, it is assumed that the user's browser is Chrome (Android) or Safari (iOS).

Document signing works as follows:

1. The user is authorized

2. The document hash is obtained

3. The digital signature is requested

4. The user's browser is redirected to the Mobile ID application

5. The digital signature is obtained

6. The signature process is deleted

7. The electronic signature is applied to the document

Authorizing the User

To sign the Word document, the user must authorize signbox for requesting, on their behalf, the generation of the digital signature. In this example, user authorization directly follows their reauthentication (i.e., it is an implicit authorization). This is established by configuration and occurs owing to the fact that the user will have to enter their PIN in their mobile device for the signature to be generated, which constitutes an explicit authorization making the first one unnecessary. Furthermore, user re-authentication does not require the user's intervention as it is performed with the same authentication flow used to create the session in the signbox app and this flow establishes SSO for the password factor.

In any case, when the user clicks on the button for signing the document (Sign), the signbox app responds with the following HTTP redirect response (see the Obtain Authorization operation):

This causes the browser to send to TRIDENT the following HTTP request specifying urn:safelayer:eidas:sign:identity:use:device as the scope of the requested authorization:

On receiving this request, TRIDENT re-authenticates the user transparently (SSO is applied) and, based on this reauthentication, it deduces that the user authorizes the signbox app to request the generation of a digital signature on their behalf. Lastly, TRIDENT provides the signbox app with the code that accredits this authorization and redirects the browser to the URL specified in the authorization request (https://signbox.safelayer.com/oauth/callback). This redirect causes the browser to send the following HTTP request to signbox:

Next, signbox uses the code it receives from the browser to request the corresponding access token (see the Obtain a Token operation):

The token is obtained in the following HTTP response:

Obtaining the Hash of the Document

Signbox must obtain the hash of the document (SHA-256) that the user wants to sign and send it to the TRIDENT for it to generate the corresponding digital signature. The TRIDENT system establishes no restriction on how this hash must be obtained. It is normally calculated using the library or framework functions for this purpose.

Let's assume the user wants to sign a document titled Business Plan 2015-2020 and that the base64 encoding of this document's hash is CagbGgL7eyNRNZAac78LDuaPggMFuw4t2jjdLenasiP=.

Requesting the Digital Signature of the Document

Once the signbox app obtains the hash of the document to be signed, it requests that the TRIDENT generates the corresponding digital signature by sending it the following HTTP message (see the Create a Process for Generating a Digital Signature on a Document with a Device operation).

As we are dealing with the on-device generation of the digital signature, signbox must notify Mobile ID that it must request from TRIDENT the hash of the document and create the corresponding digital signature. For this reason, signbox communicates to TRIDENT that it must not send any notification to the Mobile ID application (notify=false).

When TRIDENT receives the above message, it creates a signature generation process and responds with the following message (see Create a Process for Generating a Digital Signature on a Document with a Device):

Redirecting to Mobile ID

As mentioned above, it is signbox that must communicate to Mobile ID that it must generate a digital signature. Signbox does this by redirecting the user's browser to an endpoint of the Mobile ID app whose URL contains the identifier of the process created in TRIDENT for generating the signature along with several additional parameters that indicate what Mobile ID must do after generating the signature and sending it to TRIDENT. Signbox builds this URL in two steps:

• Firstly, for the base URL it takes the URL specified in the wakeup_device_uri field of the response received from the TRIDENT (bluecardMobile://signatures/9u0bdhl7679h99glqtun1je0u1), which contains the identifier of the signature generation process created.

• Secondly, it extends the base URL with a query string that contains one or more additional parameters.

The number and value of the parameters added by signbox varies depending on the user's browser:

• For Safari, it adds the successurl and failureurl parameters and assigns them as the URL values to which Mobile ID must redirect the browser after signature generation is executed either successfully or otherwise (respectively).

• For Chrome, it adds the successurl , failureurl and browserpackage parameters. The first two contain the URLs to which Mobile ID must redirect the browser after signature generation is executed either successfully or otherwise (respectively). The third is for indicating to Mobile ID that a Chrome browser is to be redirected so that the operating system (Android) does not prompt the user by displaying to them a list of all the installed browsers and that Chrome does not open a new window if it is the selected browser. The value assigned to this parameter is always: com.android.chrome.

• If the browser is not Chrome or Safari, signbox only adds the closeondone parameter to which it assigns the value 1. This tells Mobile ID that it must close (i.e., that it must stop executing) after the signature has been generated and sent to TRIDENT. As a result, signbox must, after the redirect, poll the result resource of the signature creation process to detect when the process finalizes so it can obtain the digital signature. I.e., signbox must proceed after the redirect as if the signature were generated in cross-device mode (see Wait for Signature to Be Available in the Confirming a Transaction with a Mobile Device operation).

In this example, we are assuming that the user's browser is Chrome or Safari. Let's also assume that signbox expects to be notified that the signature generation process has ended at the following URLs:

• https://signbox.safelayer.com/signatures/trustedx-eidas/success/{signature_id}

• https://signbox.safelayer.com/signatures/trustedx-eidas/fail/{signature_id}

In this case, it must concatenate the URL it received in the wakeup_device_uri field (bluecardMobile://signatures/9u0bdhl7679h99glqtun1je0u1) with one of the following text strings:

• For Safari browsers: ?successurl=https://signbox.safelayer.com/signatures/trustedx-eidas/success/9u0bdhl7679h99glqtun1je0u1&failureurl=https://signbox.safelayer.com/signatures/trustedx-eidas/fail/9u0bdhl7679h99glqtun1je0u1

• For Chrome browsers: ?successurl=https://signbox.safelayer.com/signatures/trustedx-eidas/success/9u0bdhl7679h99glqtun1je0u1&failureurl=https://signbox.safelayer.com/signatures/trustedx-eidas/fail/9u0bdhl7679h99glqtun1je0u1&browserpackage=com.android.chrome

So signbox must send the following redirect message for Safari browsers:

And the following message for Chrome browsers:

Obtaining the Digital Signature

After (via a successurl redirect) Mobile ID communicates to signbox that the digital signature has been successfully generated, signbox requests the signature from TRIDENT by sending it the following message (see Obtain the Result of a Signature Process):

And it obtains the following response:

Where the digital signature of the document is in the value element of the JSON object contained in the response body received (see Obtain the Result of a Signature Process).

Deleting the Signature Process

Once the document's digital signature has been obtained, the process used to generate the signature must be deleted. Only then can new signatures be generated with the same mobile device (i.e., with the same BlueCard Mobile instance), because until the process is deleted, all requests for generating a signature with the same device are rejected.

The signature creation process is deleted by sending the following HTTP message to the TRIDENT signature generation service (see the Delete a Signature Process operation).

Applying the Electronic Signature to the Document

Lastly, signbox applies the electronic signature to the document, including in it the digital signature received from the TRIDENT.